home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / prog_gen / guslib.zip / GUSLIB.DOC < prev    next >
Text File  |  1994-08-26  |  16KB  |  440 lines
  1.                                    GusLib
  2.                                     v1.0
  3.                                By Paul Kimbrel
  4.                                 Aug 17, 1994
  5.                                 Documentation
  6.  
  7. Short Description
  8. -------------------------------------
  9.  
  10.    GusLib is a public domain/royalty free programming library for the Gravis
  11. UltraSound sound card.  It's purpose is to allow programmers easy access to
  12. the basic functions of the GUS.  The library was mainly written for assembly
  13. language use but can be easily used with C,C++,Pascal, and other languages.
  14. It's features are:
  15.  
  16.          Direct DRAM I/O functions
  17.          DMA DRAM Output
  18.          Playback routines
  19.          Register I/O functions
  20.  
  21.    This library is designed primarily for output only.  Some functions could
  22. be used for input as well, though programming experience with the GUS would
  23. be required.
  24.  
  25.  
  26. Disclaimer
  27. -------------------------------------
  28.  
  29.    This program is given as is.  It is subject to change with out notice or
  30. permission.  I make no claims as to it's usability or workability.  I've made
  31. all attempts to test it as much as possible, but I claim no responsibility
  32. for any damages caused by this program.  In other words, it works here, so
  33. if doesn't work there, I can't help it.
  34.  
  35. Enough of the bad guy stuff:
  36.  
  37.    I'll be happy to help with any problems and would like to know if any
  38. flaws in the programming are found.  I'm always looking to improve my
  39. programs, so if you have any recommendations, please get a hold of me and
  40. let me know.
  41.    As far as it's status as a program, it's public domain which means you
  42. can do just about anything to it you want.  I encourage you to dig into the
  43. code and make your alterations to it as you wish.  Copy the code, use it in
  44. other programs, use it as a reference for other GUS applications, whatever.
  45. This program is yours to do with as you please.  Use it in your games,
  46. applications, etc., and don't worry about royalty or credit (although, just
  47. mentioning my name would be nice <g>).  If you do use my program in any of
  48. your applications, please drop me a note, just so I can keep track of things
  49. (and for personal gratification).
  50.  
  51.  
  52. Files
  53. -------------------------------------
  54.  
  55.    The following files are included in the GUSLIB library:
  56.  
  57.       GUSLIB.ASM   - Source code to GUSLIB
  58.       GUSLIB.OBJ   - Object code to GUSLIB for linking
  59.       GUSLIB.LIB   - Library file to GUSLIB for linking
  60.       GUSLIB.DOC   - Documentation for GUSLIB
  61.       PLAYVOC.EXE  - Sample program using GUSLIB (plays back .VOC files)
  62.       PLAYVOC.ASM  - Sample source code using GUSLIB
  63.  
  64.  
  65. Stuff that might be important (?)
  66. -------------------------------------
  67.  
  68.    Okay, I'll admit it - I hate commenting my programs - especially when I've
  69. been working for a solid week on it.  It gets to the point of "I could care
  70. less if I know how it works just so long as it works."  I'm sitting here
  71. with an actual working model on my computer and really don't want to go
  72. through and comment, so I'm going to let it be for now.  However, you can
  73. look for more comments in future revisions of the program (I can almost
  74. guarantee that there will be).
  75.    If you have any questions at all about the program, you can find me
  76. in the 80XXX echo on Fidonet (as Paul Kimbrel), you can net-mail me at
  77. 1:232/10 (again, to Paul Kimbrel), or e-mail me via the internet at
  78. dkimbrel@heartland.bradley.edu
  79.    All answer ALL questions even if it's to say that I haven't the foggiest
  80. idea what-so-ever.  I'll be working on a better version, but this will
  81. at least get some people (including myself) working.  I hope you find
  82. some kind of usefulness from this program.
  83.  
  84.  
  85. An IMPORTANT note concerning the DMA channels!   - MUST READ!!!!!
  86. -------------------------------------
  87.  
  88.    Please note that the only two channels that this program will work with
  89. are the 8 bit channels (1 and 3).  GUSLIB will allow for the 16 bit channels
  90. (5,6 and 7), yet I've never worked with them before.  As a result, I make
  91. NO assumtions as to if they work or not.  If you want to try - go for it,
  92. just let it be known that I have tried (yet)...
  93.  
  94.  
  95. Functions
  96. -------------------------------------
  97.  
  98.    To use these functions, simply fill the BX register with the function
  99. number and all other registers with the appropriate information (depending
  100. on the function).  Next, call the procedure GUSLIB.  When the function has
  101. been executed, a return code will come back in the AX register.  If AX
  102. reads 00h, then the function was executed successfully.  Otherwise, AX
  103. contains the error code.
  104.  
  105. Function 00h - Init_Gus
  106. -------------------------------------
  107. Short Description:  Initializes and sets up the GUS
  108.  
  109. Registers on entry:
  110.    BX = 0000h
  111.  
  112. Registers on return:
  113.    AX = Error Code   -  00h - No Error
  114.                         01h - Bad Environmental Variable
  115.                         02h - Illegal IRQ in Environmental Variable
  116.                         03h - Illegal DMA channel in Environmental Variable
  117.                         04h - GUS Reset error
  118.                         05h - DRAM I/O Error
  119.  
  120. Extended Description:
  121.  
  122.    This function preforms several tasks.  It first searches and processes the
  123. 'ULTRASND=' environmental variable.  Then it checks to make sure that all the
  124. information in the variable is correct.  Third, it resets the GUS.  Fourth,
  125. it makes sure that the DRAM is okay.  Finally, it sets up the library's
  126. ISR for the IRQ and programs the computer's PIC (how's THAT for initials!).
  127.    When the ISR is setup, your program MUST run the deinitialization function
  128. do undo what the initialization does.  The best thing to do is write your
  129. program to ALWAYS execute the deinitialation function before it exits.  The
  130. functions are made so that it won't undo the ISR if it isn't set up.  In
  131. other words, if you call the deinitalization function and there's nothing
  132. for it to do, it'll automatically return with out doing anything, making it
  133. easier for you to keep track of things.
  134.  
  135.  
  136. Function 01h - Deinit_Gus
  137. -------------------------------------
  138. Short Description:  Deinitializes and shuts down the GUS
  139.  
  140. Registers on entry:
  141.    BX = 0001h
  142.  
  143. Registers on return:
  144.    None
  145.  
  146. Extended Description:
  147.  
  148.    This function basically undoes what function 00h does.  If function 00h
  149. isn't executed, then this function will automatically return with out doing
  150. anything.  It's best to call this function right before you exit no matter
  151. what the situation is.  This makes keeping track of the initialization
  152. process easier (IOW - you really don't have to).
  153.  
  154.  
  155. Function 02h - Poke
  156. -------------------------------------
  157. Short Description:  Pokes data directly into the GUS's memory.
  158.  
  159. Registers on entry:
  160.       BX = 0002h
  161.       AL = Value to poke
  162.    SI:DI = Linear Address in GUS memory.
  163.  
  164. Registers on return:
  165.    None
  166.  
  167. Extended Description:
  168.  
  169.    This function pokes data directly into the GUS's DRAM.  SI:DI point to
  170. the absolute linear address.  Keep in mind that the GUS can only address
  171. 1 MEG of memory, so only the lower 20 bits should contain data; all other
  172. bits should be set to 0. 
  173.    NOTE: The value in AL is put into memory AS IS.  There is no two's-
  174. compliment conversion in this function.  If a conversion is necessary, you
  175. must do it to the value before you call this function.
  176.  
  177.  
  178. Function 03h - Peek
  179. -------------------------------------
  180. Short Description:  Peeks data directly from the GUS's memory.
  181.  
  182. Registers on entry:
  183.    SI:DI = Linear Address in GUS memory
  184.  
  185. Registers on return:
  186.    BX = 0003h
  187.    AL = Data at SI:DI
  188.  
  189. Extended Description:
  190.  
  191.    This function peeks data directly from the GUS's memory.  It's address
  192. scheme is the same as that in function 02h.
  193.    NOTE: The value returned in AL is read AS IS.  There is no two's-
  194. compliment conversion in this function.  If a conversion is necessary, you
  195. must do it to the value after you call this function.
  196.  
  197.  
  198. Function 04h - Set_Active
  199. -------------------------------------
  200. Short Description:  Sets the number of active voices on the GUS.
  201.  
  202. Registers on entry:
  203.    BX = 0004h
  204.    AL = Number of Pages (14-32)
  205.  
  206. Registers on return:
  207.    None
  208.  
  209. Extended Description:
  210.  
  211.    This function sets the number of active voices on the GUS.  An explanation
  212. of this function is beyond the scope of this documentation.  Just keep in
  213. mind that you don't using any voices beyond the number that you have set
  214. with this function.  NOTE:  The fewer voices you have, the better the sound
  215. quality will be.  For more information, see the Gravis Ultrasound SDK.
  216.  
  217.  
  218. Function 05h - Download_Sound
  219. -------------------------------------
  220. Short Description:  Uses PC's DMA to send a sound sample to GUS's memory.
  221.  
  222. Registers on entry:
  223.       BX = 0005h
  224.       CL = Wait Toggle (0 = no; 1 = yes)
  225.       DI = GUS DRAM Address (upper 16 bits)
  226.    ES:SI = PC segment:offset address of sample
  227.    DX:AX = Size of sample
  228.  
  229. Registers on return:
  230.    AX = Error Code   -  00h - No Error
  231.                         01h - KeyBoard interrupt (if CL = 1 on entry)
  232.                         02h - DMA still busy
  233.  
  234. Extended Description:
  235.  
  236.    This dumps a sample that is stored in PC memory to the GUS memory via
  237. the DMA channel.  Note that the GUS DRAM Address (in DI) is only the upper
  238. 16 bits of the address.  Since the entire linear address is 20 bits, you must
  239. take your absolute address and divide it by 16 (that's 16 decimal).  As you
  240. may have noticed, your DMA address will have to on a 16 byte boundary.
  241.    The wait toggle specifies to the routine if you want to it to wait until
  242. the DMA is done or to just return immediately.
  243.  
  244. CASE: CL = 0
  245.  
  246.    The routine will return as soon as the DMA has started its transfer.  No
  247. other DMA transfers can take place until the DMA is finished.  To check the
  248. status of the DMA, execute function 6 or re-execute this function.  If you
  249. re-execute this function and get an error code of 2, then the DMA is still
  250. busy.
  251.  
  252. CASE: CL = 1
  253.  
  254.    The routine will wait until the DMA has finished its transfer before
  255. returning.  For safety purposes, the program checks the keyboard during the
  256. wait.  If a key is hit, the function will return and will send back an
  257. error code of 1.
  258.  
  259.  
  260. Function 06h - Dma_Status
  261. -------------------------------------
  262. Short Description:  Checks on the status of the DMA download (function 5)
  263.  
  264. Registers on entry:
  265.    BX = 0006h
  266.  
  267. Registers on return:
  268.    AX = Status
  269.  
  270. Extended Description:
  271.  
  272.    Returns the status of the DMA download (function 5).  It returns a value
  273. of 0 if the DMA is free and available for downloading.  If it returns a value
  274. of 1, a DMA transfer is taking place and the channel is busy.
  275.  
  276.  
  277. Function 07h - Set_Volume
  278. -------------------------------------
  279. Short Description:  Sets the volume of a specific voice.
  280.  
  281. Registers on entry:
  282.    BX = 0007h
  283.    AX = Volume (0-4095)
  284.    CL = Voice (0-active voices)
  285.  
  286. Registers on return:
  287.    None
  288.  
  289. Extended Description:
  290.  
  291.    NOTE: The voice ranges from 0 to the number of active voices-1.  For
  292. example, if the number of active voices is 14, then the available voices
  293. would be 0-13.  Likewise, if the number of active voices is 32, then
  294. the available voices would be 0-31.
  295.  
  296.  
  297. Function 08h - Set_Freq
  298. -------------------------------------
  299. Short Description:  Sets the sampling frequency of a specific voice.
  300.  
  301. Registers on entry:
  302.    BX = 0008h
  303.    AX = Frequency (1-44100)
  304.    CL = Voice
  305.  
  306. Registers on return:
  307.    None
  308.  
  309. Extended Description:
  310.  
  311.    NOTE: The voice ranges from 0 to the number of active voices-1.  For
  312. example, if the number of active voices is 14, then the available voices
  313. would be 0-13.  Likewise, if the number of active voices is 32, then
  314. the available voices would be 0-31.
  315.  
  316. Function 09h - Set_Loop
  317. -------------------------------------
  318. Short Description:  Sets the loop back condition of the specific voice.
  319.  
  320. Registers on entry:
  321.    BX = 0009h
  322.    AL = Loop control register value (recommended value = 3)
  323.    CL = Voice
  324.  
  325. Registers on return:
  326.    None
  327.  
  328. Extended Description:
  329.  
  330.    NOTE: The voice ranges from 0 to the number of active voices-1.  For
  331. example, if the number of active voices is 14, then the available voices
  332. would be 0-13.  Likewise, if the number of active voices is 32, then
  333. the available voices would be 0-31.
  334.    NOTE: Loop control is beyond the scope of this manual.  For more
  335. information on loop control, read the Gravis Ultrasound SDK.  To disable
  336. the loop control, write the value 3 to the function.  This is the
  337. recommended action before using a voice (to clear any old values).
  338.  
  339.  
  340. Function 0ah - Set_Start
  341. -------------------------------------
  342. Short Description:  Sets the starting address (in GUS memory) of the sample.
  343.  
  344. Registers on entry:
  345.       BX = 000ah
  346.    DX:AX = Linear 20-bit address in GUS memory
  347.       CL = Voice
  348.  
  349. Registers on return:
  350.    None
  351.  
  352. Extended Description:
  353.  
  354.    NOTE: The voice ranges from 0 to the number of active voices-1.  For
  355. example, if the number of active voices is 14, then the available voices
  356. would be 0-13.  Likewise, if the number of active voices is 32, then
  357. the available voices would be 0-31.
  358.    This sets the starting location for the particular voice.  GUSLIB auto-
  359. matically adjusts the <current address> register to fit this value.  When
  360. you start playback of the voice, the playback will start at the value
  361. in DX:AX.  When the voice has stopped or has been stopped (manually), GUSLIB
  362. will readjust the <current address> register so that it will restart at
  363. this address each time.
  364.  
  365.  
  366. Function 0bh - Set_End
  367. -------------------------------------
  368. Short Description:  Sets the ending address (in GUS memory) of the sample.
  369.  
  370. Registers on entry:
  371.       BX = 000bh
  372.    DX:AX = Linear 20-bit address in GUS memory
  373.       CL = Voice
  374.  
  375. Registers on return:
  376.    None
  377.  
  378. Extended Description:
  379.  
  380.    NOTE: The voice ranges from 0 to the number of active voices-1.  For
  381. example, if the number of active voices is 14, then the available voices
  382. would be 0-13.  Likewise, if the number of active voices is 32, then
  383. the available voices would be 0-31.
  384.    This sets the ending address of the voice.  When the playback routine
  385. is executed, the GUS will start playback at the <start address> and will
  386. stop when it reaches this address.
  387.  
  388.  
  389. Function 0ch - Play_Voice
  390. -------------------------------------
  391. Short Description:  Starts playback of a specific voice
  392.  
  393. Registers on entry:
  394.    BX = 000ch
  395.    AH = Control register (Use 00h for normal operation)
  396.    AL = Voice
  397.  
  398. Registers on return:
  399.    None
  400.  
  401. Extended Description:
  402.  
  403.    This function starts the playback for a specific voice.  To start a normal
  404. playback (forward direction, no loop, irq's on, etc.),  Simply write 00h
  405. to the Control register (in AH).  The function will filter out unwanted
  406. information in the control register and set important information, so only
  407. worry about those bits in which you can modify.  The operation of the
  408. control register is beyond the scope of this document;  Please refer to
  409. Gravis Ultrasound SDK for more information.
  410.  
  411.  
  412. Function 0dh - Stop_Voice
  413. -------------------------------------
  414. Short Description:  Manually stops the playback of a specific voice.
  415.  
  416. Registers on entry:
  417.    BX = 000dh
  418.    AL = Voice
  419.  
  420. Registers on return:
  421.    None
  422.  
  423. Extended Description:
  424.  
  425.    This function will manually stop and reset the specified voice.
  426.  
  427.  
  428. Function 0eh - Voice_Status
  429. -------------------------------------
  430. Short Description:  Returns the playback status of a specific voice.
  431.  
  432. Registers on entry:
  433.    BX = 000eh
  434.    AL = Voice
  435.  
  436. Registers on return:
  437.    AX = Status  -  00h = Voice is in playback mode
  438.                    01h = Voice has stopped (not in playback mode) 
  439.  
  440.